{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5c1c0a7f",
   "metadata": {},
   "source": [
    "# 函数参数的查看方法\n",
    "\n",
    "本教程介绍在 VSCode 中查看 Python 函数参数的多种方法。"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e1e4ee3",
   "metadata": {},
   "source": [
    "## 1. 鼠标悬停查看(Hover)\n",
    "\n",
    "### 1.1 操作步骤\n",
    "1. 将鼠标移动到函数名上(如 `fillna`)\n",
    "2. 等待约 0.5 秒,会自动弹出提示框\n",
    "3. 提示框会显示:\n",
    "   - 函数签名(包含所有参数)\n",
    "   - 参数类型提示\n",
    "   - 简短的功能说明\n",
    "   - 参数默认值\n",
    "\n",
    "### 1.2 示例演示"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8abd4a99",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>A</th>\n",
       "      <th>B</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1.0</td>\n",
       "      <td>4.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>3.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     A    B\n",
       "0  1.0  4.0\n",
       "1  0.0  5.0\n",
       "2  3.0  0.0"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "# 示例数据\n",
    "data = pd.DataFrame({'A': [1, None, 3], 'B': [4, 5, None]})\n",
    "\n",
    "# 将鼠标悬停在 fillna 上,会看到完整的参数列表\n",
    "data.fillna(value=0)  "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b4b678ad",
   "metadata": {},
   "source": [
    "## 2. 参数提示(Parameter Hints)\n",
    "\n",
    "### 2.1 触发方式\n",
    "- 输入函数名和左括号 `(` 后自动显示\n",
    "\n",
    "### 2.2 特点\n",
    "- 会高亮当前正在输入的参数\n",
    "- 显示参数类型和默认值\n",
    "- 可以看到参数的顺序"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "337d11cb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 当你输入左括号时,会自动显示参数提示\n",
    "data.fillna()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06484c4b",
   "metadata": {},
   "source": [
    "## 3. 查看完整文档\n",
    "\n",
    "### 3.1 使用 help() 函数"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "e1dfb0bf",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method fillna in module pandas.core.generic:\n",
      "\n",
      "fillna(\n",
      "    value: 'Hashable | Mapping | Series | DataFrame | None' = None,\n",
      "    *,\n",
      "    method: 'FillnaOptions | None' = None,\n",
      "    axis: 'Axis | None' = None,\n",
      "    inplace: 'bool_t' = False,\n",
      "    limit: 'int | None' = None,\n",
      "    downcast: 'dict | None | lib.NoDefault' = <no_default>\n",
      ") -> 'Self | None' method of pandas.core.frame.DataFrame instance\n",
      "    Fill NA/NaN values using the specified method.\n",
      "\n",
      "    Parameters\n",
      "    ----------\n",
      "    value : scalar, dict, Series, or DataFrame\n",
      "        Value to use to fill holes (e.g. 0), alternately a\n",
      "        dict/Series/DataFrame of values specifying which value to use for\n",
      "        each index (for a Series) or column (for a DataFrame).  Values not\n",
      "        in the dict/Series/DataFrame will not be filled. This value cannot\n",
      "        be a list.\n",
      "    method : {'backfill', 'bfill', 'ffill', None}, default None\n",
      "        Method to use for filling holes in reindexed Series:\n",
      "\n",
      "        * ffill: propagate last valid observation forward to next valid.\n",
      "        * backfill / bfill: use next valid observation to fill gap.\n",
      "\n",
      "        .. deprecated:: 2.1.0\n",
      "            Use ffill or bfill instead.\n",
      "\n",
      "    axis : {0 or 'index'} for Series, {0 or 'index', 1 or 'columns'} for DataFrame\n",
      "        Axis along which to fill missing values. For `Series`\n",
      "        this parameter is unused and defaults to 0.\n",
      "    inplace : bool, default False\n",
      "        If True, fill in-place. Note: this will modify any\n",
      "        other views on this object (e.g., a no-copy slice for a column in a\n",
      "        DataFrame).\n",
      "    limit : int, default None\n",
      "        If method is specified, this is the maximum number of consecutive\n",
      "        NaN values to forward/backward fill. In other words, if there is\n",
      "        a gap with more than this number of consecutive NaNs, it will only\n",
      "        be partially filled. If method is not specified, this is the\n",
      "        maximum number of entries along the entire axis where NaNs will be\n",
      "        filled. Must be greater than 0 if not None.\n",
      "    downcast : dict, default is None\n",
      "        A dict of item->dtype of what to downcast if possible,\n",
      "        or the string 'infer' which will try to downcast to an appropriate\n",
      "        equal type (e.g. float64 to int64 if possible).\n",
      "\n",
      "        .. deprecated:: 2.2.0\n",
      "\n",
      "    Returns\n",
      "    -------\n",
      "    Series/DataFrame or None\n",
      "        Object with missing values filled or None if ``inplace=True``.\n",
      "\n",
      "    See Also\n",
      "    --------\n",
      "    ffill : Fill values by propagating the last valid observation to next valid.\n",
      "    bfill : Fill values by using the next valid observation to fill the gap.\n",
      "    interpolate : Fill NaN values using interpolation.\n",
      "    reindex : Conform object to new index.\n",
      "    asfreq : Convert TimeSeries to specified frequency.\n",
      "\n",
      "    Examples\n",
      "    --------\n",
      "    >>> df = pd.DataFrame([[np.nan, 2, np.nan, 0],\n",
      "    ...                    [3, 4, np.nan, 1],\n",
      "    ...                    [np.nan, np.nan, np.nan, np.nan],\n",
      "    ...                    [np.nan, 3, np.nan, 4]],\n",
      "    ...                   columns=list(\"ABCD\"))\n",
      "    >>> df\n",
      "         A    B   C    D\n",
      "    0  NaN  2.0 NaN  0.0\n",
      "    1  3.0  4.0 NaN  1.0\n",
      "    2  NaN  NaN NaN  NaN\n",
      "    3  NaN  3.0 NaN  4.0\n",
      "\n",
      "    Replace all NaN elements with 0s.\n",
      "\n",
      "    >>> df.fillna(0)\n",
      "         A    B    C    D\n",
      "    0  0.0  2.0  0.0  0.0\n",
      "    1  3.0  4.0  0.0  1.0\n",
      "    2  0.0  0.0  0.0  0.0\n",
      "    3  0.0  3.0  0.0  4.0\n",
      "\n",
      "    Replace all NaN elements in column 'A', 'B', 'C', and 'D', with 0, 1,\n",
      "    2, and 3 respectively.\n",
      "\n",
      "    >>> values = {\"A\": 0, \"B\": 1, \"C\": 2, \"D\": 3}\n",
      "    >>> df.fillna(value=values)\n",
      "         A    B    C    D\n",
      "    0  0.0  2.0  2.0  0.0\n",
      "    1  3.0  4.0  2.0  1.0\n",
      "    2  0.0  1.0  2.0  3.0\n",
      "    3  0.0  3.0  2.0  4.0\n",
      "\n",
      "    Only replace the first NaN element.\n",
      "\n",
      "    >>> df.fillna(value=values, limit=1)\n",
      "         A    B    C    D\n",
      "    0  0.0  2.0  2.0  0.0\n",
      "    1  3.0  4.0  NaN  1.0\n",
      "    2  NaN  1.0  NaN  3.0\n",
      "    3  NaN  3.0  NaN  4.0\n",
      "\n",
      "    When filling using a DataFrame, replacement happens along\n",
      "    the same column names and same indices\n",
      "\n",
      "    >>> df2 = pd.DataFrame(np.zeros((4, 4)), columns=list(\"ABCE\"))\n",
      "    >>> df.fillna(df2)\n",
      "         A    B    C    D\n",
      "    0  0.0  2.0  0.0  0.0\n",
      "    1  3.0  4.0  0.0  1.0\n",
      "    2  0.0  0.0  0.0  NaN\n",
      "    3  0.0  3.0  0.0  4.0\n",
      "\n",
      "    Note that column D is not affected since it is not present in df2.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# 使用 help() 函数查看完整文档\n",
    "help(data.fillna)\n",
    "\n",
    "# 输出包含:\n",
    "# - 函数签名\n",
    "# - 参数说明(Parameters)\n",
    "# - 返回值说明(Returns)\n",
    "# - 使用示例(Examples)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad6df674",
   "metadata": {},
   "source": [
    "### 3.2 使用 Jupyter 魔法命令"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a57eb87",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[31mSignature:\u001b[39m\n",
      "data.fillna(\n",
      "    value: \u001b[33m'Hashable | Mapping | Series | DataFrame | None'\u001b[39m = \u001b[38;5;28;01mNone\u001b[39;00m,\n",
      "    *,\n",
      "    method: \u001b[33m'FillnaOptions | None'\u001b[39m = \u001b[38;5;28;01mNone\u001b[39;00m,\n",
      "    axis: \u001b[33m'Axis | None'\u001b[39m = \u001b[38;5;28;01mNone\u001b[39;00m,\n",
      "    inplace: \u001b[33m'bool_t'\u001b[39m = \u001b[38;5;28;01mFalse\u001b[39;00m,\n",
      "    limit: \u001b[33m'int | None'\u001b[39m = \u001b[38;5;28;01mNone\u001b[39;00m,\n",
      "    downcast: \u001b[33m'dict | None | lib.NoDefault'\u001b[39m = <no_default>,\n",
      ") -> \u001b[33m'Self | None'\u001b[39m\n",
      "\u001b[31mDocstring:\u001b[39m\n",
      "Fill NA/NaN values using the specified method.\n",
      "\n",
      "Parameters\n",
      "----------\n",
      "value : scalar, dict, Series, or DataFrame\n",
      "    Value to use to fill holes (e.g. 0), alternately a\n",
      "    dict/Series/DataFrame of values specifying which value to use for\n",
      "    each index (for a Series) or column (for a DataFrame).  Values not\n",
      "    in the dict/Series/DataFrame will not be filled. This value cannot\n",
      "    be a list.\n",
      "method : {'backfill', 'bfill', 'ffill', None}, default None\n",
      "    Method to use for filling holes in reindexed Series:\n",
      "\n",
      "    * ffill: propagate last valid observation forward to next valid.\n",
      "    * backfill / bfill: use next valid observation to fill gap.\n",
      "\n",
      "    .. deprecated:: 2.1.0\n",
      "        Use ffill or bfill instead.\n",
      "\n",
      "axis : {0 or 'index'} for Series, {0 or 'index', 1 or 'columns'} for DataFrame\n",
      "    Axis along which to fill missing values. For `Series`\n",
      "    this parameter is unused and defaults to 0.\n",
      "inplace : bool, default False\n",
      "    If True, fill in-place. Note: this will modify any\n",
      "    other views on this object (e.g., a no-copy slice for a column in a\n",
      "    DataFrame).\n",
      "limit : int, default None\n",
      "    If method is specified, this is the maximum number of consecutive\n",
      "    NaN values to forward/backward fill. In other words, if there is\n",
      "    a gap with more than this number of consecutive NaNs, it will only\n",
      "    be partially filled. If method is not specified, this is the\n",
      "    maximum number of entries along the entire axis where NaNs will be\n",
      "    filled. Must be greater than 0 if not None.\n",
      "downcast : dict, default is None\n",
      "    A dict of item->dtype of what to downcast if possible,\n",
      "    or the string 'infer' which will try to downcast to an appropriate\n",
      "    equal type (e.g. float64 to int64 if possible).\n",
      "\n",
      "    .. deprecated:: 2.2.0\n",
      "\n",
      "Returns\n",
      "-------\n",
      "Series/DataFrame or None\n",
      "    Object with missing values filled or None if ``inplace=True``.\n",
      "\n",
      "See Also\n",
      "--------\n",
      "ffill : Fill values by propagating the last valid observation to next valid.\n",
      "bfill : Fill values by using the next valid observation to fill the gap.\n",
      "interpolate : Fill NaN values using interpolation.\n",
      "reindex : Conform object to new index.\n",
      "asfreq : Convert TimeSeries to specified frequency.\n",
      "\n",
      "Examples\n",
      "--------\n",
      ">>> df = pd.DataFrame([[np.nan, 2, np.nan, 0],\n",
      "...                    [3, 4, np.nan, 1],\n",
      "...                    [np.nan, np.nan, np.nan, np.nan],\n",
      "...                    [np.nan, 3, np.nan, 4]],\n",
      "...                   columns=list(\"ABCD\"))\n",
      ">>> df\n",
      "     A    B   C    D\n",
      "0  NaN  2.0 NaN  0.0\n",
      "1  3.0  4.0 NaN  1.0\n",
      "2  NaN  NaN NaN  NaN\n",
      "3  NaN  3.0 NaN  4.0\n",
      "\n",
      "Replace all NaN elements with 0s.\n",
      "\n",
      ">>> df.fillna(0)\n",
      "     A    B    C    D\n",
      "0  0.0  2.0  0.0  0.0\n",
      "1  3.0  4.0  0.0  1.0\n",
      "2  0.0  0.0  0.0  0.0\n",
      "3  0.0  3.0  0.0  4.0\n",
      "\n",
      "Replace all NaN elements in column 'A', 'B', 'C', and 'D', with 0, 1,\n",
      "2, and 3 respectively.\n",
      "\n",
      ">>> values = {\"A\": 0, \"B\": 1, \"C\": 2, \"D\": 3}\n",
      ">>> df.fillna(value=values)\n",
      "     A    B    C    D\n",
      "0  0.0  2.0  2.0  0.0\n",
      "1  3.0  4.0  2.0  1.0\n",
      "2  0.0  1.0  2.0  3.0\n",
      "3  0.0  3.0  2.0  4.0\n",
      "\n",
      "Only replace the first NaN element.\n",
      "\n",
      ">>> df.fillna(value=values, limit=1)\n",
      "     A    B    C    D\n",
      "0  0.0  2.0  2.0  0.0\n",
      "1  3.0  4.0  NaN  1.0\n",
      "2  NaN  1.0  NaN  3.0\n",
      "3  NaN  3.0  NaN  4.0\n",
      "\n",
      "When filling using a DataFrame, replacement happens along\n",
      "the same column names and same indices\n",
      "\n",
      ">>> df2 = pd.DataFrame(np.zeros((4, 4)), columns=list(\"ABCE\"))\n",
      ">>> df.fillna(df2)\n",
      "     A    B    C    D\n",
      "0  0.0  2.0  0.0  0.0\n",
      "1  3.0  4.0  0.0  1.0\n",
      "2  0.0  0.0  0.0  NaN\n",
      "3  0.0  3.0  0.0  4.0\n",
      "\n",
      "Note that column D is not affected since it is not present in df2.\n",
      "\u001b[31mFile:\u001b[39m      e:\\anaconda\\lib\\site-packages\\pandas\\core\\generic.py\n",
      "\u001b[31mType:\u001b[39m      method"
     ]
    }
   ],
   "source": [
    "# 使用 ? 查看文档\n",
    "?data.fillna       \n",
    "\n",
    "# 使用 ?? 查看源码(如果支持),但是一般用ctrl或者断点调试来看-----有点传统编程的感觉了\n",
    "# ??data.fillna"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f88613d2",
   "metadata": {},
   "source": [
    "### 3.3 help() 与 ? 的区别\n",
    "\n",
    "虽然两者都用于查看文档,但它们的输出格式和内容有所不同:\n",
    "\n",
    "#### help() 函数\n",
    "- **来源:** Python 内置函数\n",
    "- **格式:** 纯文本格式,在终端中显示\n",
    "- **内容:** 读取对象的 `__doc__` 属性(docstring)\n",
    "- **显示:** 使用分页器显示(如 `less`),可以上下滚动\n",
    "- **退出:** 按 `q` 退出查看\n",
    "- **适用:** 任何 Python 环境(包括普通 Python 解释器)\n",
    "\n",
    "#### ? 魔法命令\n",
    "- **来源:** IPython/Jupyter 特有功能\n",
    "- **格式:** 带格式的文本,可能包含颜色高亮\n",
    "- **内容:** 除了 docstring,还包括:\n",
    "  - 对象类型信息\n",
    "  - 定义所在文件\n",
    "  - 源代码位置\n",
    "  - 更丰富的格式化\n",
    "- **显示:** 在 Jupyter 中以弹出窗口或下方面板显示\n",
    "- **适用:** 仅在 IPython/Jupyter 环境中可用"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74e43da0",
   "metadata": {},
   "source": [
    "方法总结对比\n",
    "\n",
    "| 方法 | 快捷键 | 优点 | 适用场景 |\n",
    "|------|--------|------|----------|\n",
    "| 鼠标悬停 | 无 | 自动、快速 | 快速查看参数列表 |\n",
    "| 强制悬停 | Ctrl+K Ctrl+I | 主动触发 | 悬停不显示时 |\n",
    "| 参数提示 | Ctrl+Shift+Space | 高亮当前参数 | 输入参数时 |\n",
    "| help() | 无 | 最详细、兼容性好 | 需要完整文档时 |\n",
    "| ? | 无 | Jupyter 友好、格式美观 | Jupyter 环境中 |\n",
    "| ?? | 无 | 可查看源码 | 深入理解实现 |\n",
    "| 跳转定义 | F12 | 直接查看源码 | 深入理解实现 |\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
